#ifndef IMCPCAPABILITY_H
#define IMCPCAPABILITY_H

#include "IMcpCapability.h"

#include <memory>

#include <QString>
#include <QJsonObject>

class Task;
struct CapabilityMethod;

/**
 * @brief Interface for method builder pattern
 * 
 * Provides a fluent interface for building method configurations with validation.
 * Ensures that all required fields are set before building the final method object.
 */
class IMethodBuilder
{
public:
    virtual ~IMethodBuilder() = default;

    /**
     * @brief Set the method name
     * @param name - method name
     * @return IMethodBuilder& - reference to this builder for chaining
     */
    virtual IMethodBuilder& setName(const QString& name) = 0;

    /**
     * @brief Set the method title
     * @param title - method title
     * @return IMethodBuilder& - reference to this builder for chaining
     */
    virtual IMethodBuilder& setTitle(const QString& title) = 0;

    /**
     * @brief Set the method description
     * @param description - method description
     * @return IMethodBuilder& - reference to this builder for chaining
     */
    virtual IMethodBuilder& setDescription(const QString& description) = 0;

    /**
     * @brief Set a method parameter
     * @param name - parameter name
     * @param parameters - parameter configuration as JSON object
     * @param msg - optional pointer to QString that will be set to error message if parameter is not valid
     * @return IMethodBuilder& - reference to this builder for chaining
     * 
     * If the parameter name is not accepted by the specific builder type,
     * this method should do nothing and return the builder unchanged, and
     * if msg is not nullptr, it should be set to "Unknown parameter name: <name>".
     */
    virtual IMethodBuilder& setParameters(const QString& name, const QJsonObject& parameters, QString* msg = nullptr) = 0;

    /**
     * @brief Set the method task
     * @param task - Shared pointer to the task object
     * @return IMethodBuilder& - Reference to this builder for chaining
     */
    virtual IMethodBuilder& setMethodTask(std::shared_ptr<Task> task) = 0;

    /**
     * @brief Build the final method configuration
     * @param msg - optional pointer to QString that will be set to error message if build failed
     * @return CapabilityMethod - complete method configuration with task, or empty CapabilityMethod if build failed
     */
    virtual CapabilityMethod build(QString* msg = nullptr) = 0;

    /**
     * @brief Clear all data and reset the builder to initial state
     */
    virtual void clear() = 0;

protected:
    /**
     * @brief Check if all required fields are complete
     * @return bool - true if all required fields are set, false otherwise
     */
    virtual bool checkComplete() const = 0;
};

#endif // IMCPCAPABILITY_H
